Amiga Tools 2

home *** CD-ROM | disk | FTP | other *** search

/ Amiga Tools 2 / Amiga Tools 2.iso / tools / jade / man / jade.info-9 (.txt) < prev next >

Wrap

GNU Info File | 1995-03-09 | 50KB | 961 lines

This is Info file jade.info, produced by Makeinfo-1.55 from the input file jade.texi. START-INFO-DIR-ENTRY * Jade: (jade). An editor for X11 and AmigaDOS END-INFO-DIR-ENTRY This is Edition 1.3, last updated 7 October 1994, of `The Jade Manual', for Jade, Version 3.2. Jade is a text editor for X11 (on Unix) and the Amiga. Copyright 1993, 1994 John Harper. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. File: jade.info, Node: Indentation Functions, Next: Translation Functions, Prev: Transpose Functions, Up: Text Indentation Functions --------------------- - Function: indent-pos &optional POS BUFFER This function returns the *glyph* position (*note Glyph Positions::.) of the first character in the line pointed to by POS (or the cursor) which is not a TAB or SPC character. - Function: set-indent-pos INDENT-POS &optional BUFFER ONLY-SPACES Sets the indentation of the line pointed to by POS to the column pointed to by POS by putting the optimal sequence of TAB and SPC characters at the start of the line. If the ONLY-SPACES argument is non-`nil' no TAB characters will be used. - Command: indent-to COLUMN &optional ONLY-SPACES This function inserts enough TAB and SPC characters to move the cursor to glyph column COLUMN. If the ONLY-SPACES argument is non-`nil' no TAB characters are used. Note that COLUMN counts from zero. When called interactively the COLUMN argument is either the numeric value of the prefix argument or, if no prefix argument has been entered, the result of prompting for a number. - Command: tab-with-spaces This command inserts enough spaces at the cursor position to move the cursor to the next tab stop. Some major modes provide their own method of indentation (for example Lisp mode will indent Lisp programs in the proper style), see *Note Mode-Specific Indentation::. - Command: indent-line If the current buffer has a method for indentation installed, use it to indent the current line to its correct depth. - Command: newline-and-indent Insert a newline character, then indent the new line; if no function for indenting lines has been installed in this buffer a single TAB character is inserted. - Command: indent-area START-POS END-POS Uses the buffer's indentation method to indent all lines in the specified region to their correct depth. When called interactively the currently-marked block is used to get the values of the two arguments, the block is then unmarked. File: jade.info, Node: Translation Functions, Next: Search and Match Functions, Prev: Indentation Functions, Up: Text Translation Functions --------------------- - Function: translate-area START-POS END-POS TRANSLATION-TABLE &optional BUFFER This function applies the mapping TRANSLATION-TABLE to each character in the region starting at the position START-POS up to, but not including, END-POS. TRANSLATION-TABLE is a string, each character represents the mapping for an ASCII character of that character's position in the string. If the string is less than 256 characters in length any undefined characters will remain unchanged (i.e. a TRANSLATION-TABLE of `' would leave the region unaltered). - Function: translate-string STRING TRANSLATION-TABLE This function uses a similar method to that used in the `translate-area' function. Instead of applying the mapping to a region of a buffer it applies it to the string STRING. STRING is returned (after being modified). Note that the STRING really is modified, no copy is made! (translate-string "abc" upcase-table) => "ABC" - Variable: upcase-table This is a 256-character long string which may be used as a translation table to convert from lower-case to upper-case with the functions `translate-string' and `translate-area'. - Variable: downcase-table Similar to `upcase-table' except that it is used to convert from upper-case to lower-case. The following functions use the translation functions and the two translation tables described above. - Command: upcase-area START-POS END-POS &optional BUFFER Makes all alphabetic characters in the specified region of text upper-case. When called interactively uses the block marks for its arguments; note that this won't work properly with rectangular blocks. - Command: downcase-area START-POS END-POS &optional BUFFER Similar to `upcase-area' but makes all alphabetic characters lower-case. - Command: upcase-word COUNT For the next COUNT words starting at the cursor position, make their alphabetic characters upper-case. - Command: downcase-word COUNT Does the opposite of `upcase-word', makes words lower-case! - Command: capitalize-word The first character of this word (normally the one under the cursor) is made upper-case, the rest lower. File: jade.info, Node: Search and Match Functions, Next: Rectangular Editing, Prev: Translation Functions, Up: Text Searching and Matching Functions -------------------------------- The most powerful of the searching and matching functions are those using regular expressions, for details of the regexp syntax used by Jade see *Note Regular Expressions::. Note that the regexp matcher *does not work across lines*, at the moment no regexp may span more than one line. Also the regexp routines choke on NUL bytes; hopefully I'll correct these problems soon... * Menu: * Searching Buffers:: Scanning buffers for something * String Matching:: Matching regexps to text * Replacing Strings:: Replacing a found string or regexp with something else * Regexp Functions:: General regexp utility functions File: jade.info, Node: Searching Buffers, Next: String Matching, Up: Search and Match Functions Searching Buffers ................. - Function: find-next-regexp REGEXP &optional POS BUFFER IGNORE-CASE This function returns the position of the next substring in the buffer matching the regular expression string REGEXP. It starts searching at POS, or the cursor position if POS is undefined. If no match of the regexp occurs before the end of the buffer `nil' is returned. If the IGNORE-CASE argument is non-`nil' then the case of matched strings is ignored (note that character ranges are still case-significant). - Function: find-prev-regexp REGEXP &optional POS BUFFER IGNORE-CASE Similar to `find-next-regexp' except this searches in the opposite direction, from POS (or the cursor) to the *start* of the buffer. - Function: find-next-string STRING &optional POS BUFFER Scans forwards from POS (or the cursor), in BUFFER (or the current buffer), looking for a match with the string STRING. Returns the position of the next match or `nil'. Note that matches can't span more than one line. - Function: find-prev-string STRING &optional POS BUFFER A backwards-searching version of `find-next-string'. - Function: find-next-char CHARACTER &optional POS BUFFER Search forwards for an occurrence of the character CHARACTER and returns its position, or `nil' if no occurrence exists. - Function: find-prev-char CHARACTER &optional POS BUFFER This function searches backwards for an occurrence of the character CHARACTER. File: jade.info, Node: String Matching, Next: Replacing Strings, Prev: Searching Buffers, Up: Search and Match Functions String Matching ............... - Function: looking-at REGEXP &optional POS BUFFER IGNORE-CASE Returns `t' if the regular expression REGEXP matches the text at position POS in the buffer BUFFER (or the current buffer). Only the text from POS to the end of the line is matched against. - Function: regexp-match REGEXP STRING &optional IGNORE-CASE This function returns `t' if the regular expression REGEXP matches the string STRING. Note that the match is unanchored so if you want test for a match of the whole of STRING use the `^' and `$' regexp meta-characters. For example, (regexp-match "(a|b)+" "fooabababar") => t (regexp-match "^(a|b)+$" "fooabababar") => nil (regexp-match "^(a|b)+$" "ababbabba") => t When the IGNORE-CASE argument is non-`nil' the case of strings being matched is insignificant (except in character ranges). - Function: regexp-expand REGEXP STRING TEMPLATE &optional IGNORE-CASE This function matches the regular expression REGEXP against the string STRING, if the match is successful a string is created by expanding the template string TEMPLATE. For details of what meta-characters are allowed in TEMPLATE see *Note Regular Expressions::. (regexp-expand "^([a-z]+):([0-9]+)$" "foobar:42" "The \\1 is \\2.") => "The foobar is 42." - Function: regexp-match-line REGEXP &optional LINE-POS BUFFER IGNORE-CASE This function is similar to `regexp-match', instead of explicitly supplying the string to match against it is one whole line of the specified buffer, the line pointed to by LINE-POS (or the line that the cursor is on). `t' is returned if the match is successful. - Function: regexp-expand-line REGEXP TEMPLATE &optional LINE-POS BUFFER IGNORE-CASE As `regexp-match-line' is similar to `regexp-match', this function is similar to `regexp-expand'. The whole of the line at the position LINE-POS (or the cursor) is matched with the regular expression REGEXP. If the match is successful the TEMPLATE is used to expand a string which is returned. File: jade.info, Node: Replacing Strings, Next: Regexp Functions, Prev: String Matching, Up: Search and Match Functions Replacing Strings ................. - Function: replace-regexp REGEXP TEMPLATE &optional POS BUFFER IGNORE-CASE If a substring of the buffer at POS (or the cursor) matches the regular expression REGEXP the text that matched is replaced with the result of expanding the template string TEMPLATE. For details about templates see *Note Regular Expressions::. `nil' is returned if the match failed, and therefore no replacement occurred. - Function: replace-string OLD-STRING NEW-STRING &optional POS BUFFER If a substring of the buffer at POS (or the cursor) matches the string OLD-STRING it is replaced by the string NEW-STRING. If the match fails `nil' is returned, otherwise some non-`nil' value. File: jade.info, Node: Regexp Functions, Prev: Replacing Strings, Up: Search and Match Functions Regexp Functions ................ It is often useful to construct regular expressions by concatenating several strings together; the problem with doing this is you may not know if a string contains any characters which the regexp compiler reacts specially to (i.e. `*', `|', ...). Obviously these characters should be protected by a backslash, the following function will do this for you. - Function: regexp-quote STRING This function returns a new version of the string STRING, any characters in STRING which are regexp meta-characters are quoted with a backslash. If the string contains no meta-characters the original string is returned, without being copied. (regexp-quote "foo*bar+baz") => "foo\\*bar\\+baz" Note that in the above example the backslashes in the returned string are only single backslashes; the print functions print a single backslash character as `\\' so they can be read back in. This function is usually used when a part of a regexp being constructed is unknown at compile time, often provided by the user. As the section describing regexp syntax notes, the strings that parenthesised expressions match are recorded, the following two functions allow Lisp programs to access the positions of these strings. - Function: match-start &optional EXPRESSION-INDEX This function returns the position which the parenthesised expression number EXPRESSION-INDEX started at in the last successful regexp match. If EXPRESSION-INDEX is `nil' or zero the start of the whole string matched is returned instead. The returned value will either be a position object if the last match was in a buffer, or an integer if the last match was in a string (i.e. `regexp-match'). (regexp-match "foo(bar)" "xyzfoobarsaalsd") => t (match-start) => 3 (match-start 1) => 6 - Function: match-end &optional EXPRESSION-INDEX Return the position which the parenthesised expression number EXPRESSION-INDEX ended at in the last successful regexp match. If EXPRESSION-INDEX is `nil' or zero the end of the whole match is returned instead. The returned value will either be a position object if the last match was in a buffer, or an integer if the last match was in a string (i.e. `regexp-match'). (regexp-match "foo(bar)" "xyzfoobarsaalsd") => t (match-end) => 9 (match-end 1) => 9 File: jade.info, Node: Rectangular Editing, Next: Controlling Undo, Prev: Search and Match Functions, Up: Text Rectangular Editing ------------------- These functions are used to manipulate rectangular regions of buffers. Two position objects are used to define a rectangle, these represent opposite corners of the rectangle. Note that the corner on the right hand side of the rectangle specifies the column *after* the last column included in the rectangle. - Function: delete-rect START-POS END-POS &optional BUFFER This function deletes a rectangle, defined by START-POS and END-POS, from the specified buffer. - Function: copy-rect START-POS END-POS &optional BUFFER Returns a string containing the rectangle of text defined by the two positions START-POS and END-POS. Any TAB characters are expanded to SPC characters, newline characters mark the end of each line in the rectangle. - Function: cut-rect START-POS END-POS &optional BUFFER A combination of the `copy-rect' and `delete-rect' functions; it makes a copy of the rectangle's contents which is returned after the rectangle is deleted from the buffer. - Command: insert-rect STRING &optional POS BUFFER Inserts the string STRING into the buffer at the specified position, treating STRING as a rectangle of text. This means that each successive line of STRING (separated by newline characters) is inserted at the *same* column in successive lines. If the end of the buffer is reached and there is still some of the string left to insert extra lines are created at the end of the buffer. - Command: yank-rectangle &optional DONT-YANK-BLOCK This function is similar to the `yank' function (*note Insertion Functions::.), except that it uses the `insert-rect' function to insert the piece of text. File: jade.info, Node: Controlling Undo, Next: Misc Text Functions, Prev: Rectangular Editing, Up: Text Controlling Undo ---------------- For the description of one part of controlling the undo feature, the maximum size of the undo-list, see *Note Undo::. - Variable: buffer-record-undo A buffer-local variable which, when set to `nil', stops any undo-information being recorded for the buffer. When a buffer is created, this variable is always set to `t'. - Variable: buffer-undo-list This buffer-local variable stores the actual list of undo-information; each element defines one modification to the buffer. Don't try to be clever and access the contents of this list; the structure may well change in future revisions of Jade. The only thing you're allowed to do is set it to `nil', this clears all undo-information for the buffer. - Command: undo Undo every change to the contents of the buffer back to the previous command. Successive calls to this command work backwards through the buffer's undo-list. File: jade.info, Node: Misc Text Functions, Prev: Controlling Undo, Up: Text Miscellaneous Text Functions ---------------------------- - Function: empty-line-p &optional POS BUFFER This function returns `t' if the line pointed to by POS (or by the cursor) consists totally of TAB or SPC characters. File: jade.info, Node: Writing Modes, Next: Prompting, Prev: Text, Up: Programming Jade Writing Modes ============= Modes are used to customise individual buffers so that the text it contains can be edited in a special way. Each buffer has a single "Major mode", tailoring the buffer to the type of file contained in it (i.e. C source code uses `c-mode'). *Note Editing Modes::. "Minor modes" provide individual features which may be enabled and disabled individually, each buffer may have any number of minor modes enabled at once. *Note Minor Modes::. * Menu: * Writing Major Modes:: How to define a new major mode * Installing Modes:: Functions and variables used to install major modes in buffers * Writing Minor Modes:: Minor modes are totally different to major modes * Mode-Specific Indentation:: Each major mode may define its own method of indentation, * Mode-Specific Expressions:: expression handling, * Mode-Specific Comments:: and comment insertion. File: jade.info, Node: Writing Major Modes, Next: Installing Modes, Up: Writing Modes Writing Major Modes ------------------- Each major mode must define a command whose name ends in `-mode' (i.e. `c-mode', `lisp-mode', etc...). This command is called when the major mode is to be installed in the current buffer. It's first action *must* be to check for an already installed mode and remove it. The following code fragment does this, (when major-mode-kill (funcall major-mode-kill)) *All* major modes must do this! Now the major mode is free to install itself; generally this will entail setting the buffer-local values of the `mode-name', `major-mode', `major-mode-kill' and `keymap-path' variables. For example the `lisp-mode' sets these variables as follows, (setq mode-name "Lisp" major-mode 'lisp-mode major-mode-kill 'lisp-mode-kill keymap-path (cons 'lisp-mode-keymap keymap-path)) Note how the major mode's own keymap (with all the mode's local key bindings installed in it) is consed onto the front of the `keymap-path'; this ensures that mode-local bindings take precedence over bindings in the global keymaps. After installing itself a major mode should call a hook (generally called `X-mode-hook' where X is the name of the mode) to allow customisation of the mode itself. The `major-mode-kill' variable holds a function to be called when the major mode is to be removed from the current buffer; basically it should remove its keymap and set all the mode-local variables to `nil'. For example the `lisp-mode-kill' function does the following to negate the effects of the code fragment above, (setq keymap-path (delq 'lisp-mode-keymap keymap-path) major-mode nil major-mode-kill nil mode-name nil) - Variable: major-mode This buffer-local variable contains the symbol whose function definition was used to install the buffer's major mode (i.e. `c-mode', etc...). When it is `nil' the buffer uses the `generic' mode; this is simply the bog standard editor. - Variable: major-mode-kill This buffer-local variable contains the function which should be called to remove the buffer's currently installed major-mode. Note that the `kill-buffer' function calls this (if it's non-`nil') just before destroying a buffer; so if necessary, an error signalled within this function will prevent a buffer being killed. - Variable: mode-name A buffer-local variable containing the `pretty' name of the buffer's major mode, a string which will be printed in the status line. Many modes bind commands to keys with the prefix `Ctrl-c', to save each mode creating a new root keymap the buffer-local variable `ctrl-c-keymap' exists. - Variable: ctrl-c-keymap This buffer-local variable can be used by major modes to hang their keymap for the `Ctrl-c' prefix from. Simply set this variable to the keymap your mode wants to be installed after a `Ctrl-c' prefix. The definitions for many different types of modes can be found in Jade's lisp directory. File: jade.info, Node: Installing Modes, Next: Writing Minor Modes, Prev: Writing Major Modes, Up: Writing Modes Installing Modes ---------------- Before a major mode can be used to edit a buffer with it must be installed in that buffer. The most straightforward method of doing this is simply to invoke the mode's command which does this (i.e. `c-mode'). It could be a bit annoying to have to this every time a new buffer is created so the `mode-alist' variable allows major modes to be installed automatically, when the buffer is opened. - Function: init-mode BUFFER &optional STRING This function attempts to install a major mode into BUFFER. If the `major-mode' variable is non-`nil' it defines the function to call to install the mode; this function will be called. Otherwise the `mode-alist' variable is searched; each regular expression is matched against a string, when a match occurs the associated function is called to install the mode. The string matched against is defined by the first of the following choices which is not `nil' or undefined. 1. The value of the optional STRING argument. 2. The word specified on the first line of the buffer bracketed by the string `-*-'. For example if the first line contained the string `-*-Text-*-' the string `Text' would be used. 3. The value of the variable mode-name. 4. The name of the file being edited in the buffer. Note that each match is case-insensitive. - Variable: mode-alist An association list (*note Association Lists::.) defining regular expressions which associate with a particular major mode. When the `init-mode' function matches a regular expression to the string it is using to find the mode for the buffer the associated mode is installed. For example, `mode-alist' could be, (("\\.(c|h)$|^c(|-mode)$" . c-mode) ("\\.jl$|^lisp(|-mode)$" . lisp-mode) ("\\.(text|doc|txt|article|letter)$" . text-mode) ("^(text(|-mode)|(.*/|)draft)$" . text-mode) ("^indented-text(|-mode)$" . indented-text-mode) ("\\.[s]$|^asm(|-mode)$" . asm-mode) ("\\.[S]$|^asm-cpp(|-mode)$" . asm-cpp-mode) ("\\.texi(|nfo)|^texinfo(|-mode)$" . texinfo-mode)) - Function: kill-mode &optional BUFFER This function removes the major mode currently installed in the specified buffer. File: jade.info, Node: Writing Minor Modes, Next: Mode-Specific Indentation, Prev: Installing Modes, Up: Writing Modes Writing Minor Modes ------------------- Minor modes are generally harder to write properly than major modes since they have to peacefully coexist with all the other minor modes which may also be enabled in a buffer. Generally each minor mode maintains a buffer-local variable saying whether or not it's installed in the buffer. The minor mode's function usually toggles the mode on or off depending on the state of this variable. There are two functions which *must* be used to install and remove a minor mode -- `add-minor-mode' and `remove-minor-mode', see their documentation for details. Each buffer has a keymap containing the bindings of all the minor modes enabled in the buffer (the variable `minor-mode-keymap'). These bindings have to be added when the mode is enabled and removed when it is disabled. - Variable: minor-mode-list This buffer-local variable is a list of all the minor modes enabled in a buffer. - Variable: minor-mode-names This buffer-local variable contains a list of strings, each string names one of the minor modes currently enabled in the buffer. - Variable: minor-mode-keymap A buffer-local keymap to be used by minor-modes. This is only created the first time a minor mode calls `add-minor-mode' in the buffer. - Function: add-minor-mode MODE NAME &optional NO-KEYMAP This function installs a minor mode (the symbol MODE) into the current buffer. All minor modes should call this before doing anything drastic. NAME is the string to be displayed in the status line as the name of this minor mode. When NO-KEYMAP is `nil' or undefined this function ensures that the `minor-mode-keymap' variable has a valid value in this buffer. - Function: remove-minor-mode MODE NAME Removes a minor mode from the current buffer, the MODE and NAME arguments must have the same value as the arguments given to `add-minor-mode' when the mode was enabled. The following code fragment is an example minor mode taken from Jade's source code. (provide 'fill-mode) (defvar fill-column 72 "Position at which the text filling commands break lines.") (defvar fill-mode-p nil) (make-variable-buffer-local 'fill-mode-p) ;;;###autoload (defun fill-mode () "Minor mode for automatically filling lines, i.e. word-wrapping. This makes the SPC key checks if the cursor is past the fill-column. If so, the next line is started." (interactive) (if fill-mode-p (progn (setq fill-mode-p nil) (remove-minor-mode 'fill-mode "Fill") (unbind-keys minor-mode-keymap "SPC")) (add-minor-mode 'fill-mode "Fill") (setq fill-mode-p t) (bind-keys minor-mode-keymap "SPC" 'fill-mode-spc))) (defun fill-mode-spc () (interactive) (when (> (pos-col (cursor-pos)) fill-column) (let ((pos (cursor-pos))) (set-pos-col pos (1+ fill-column)) (setq pos (unless (word-start pos) (forward-word -1 pos))) (insert "\n" pos) (let ((end (left-char 1 (copy-pos pos)))) (when (equal (get-char end) ?\ ) (delete-area end pos))))) (insert " ")) File: jade.info, Node: Mode-Specific Indentation, Next: Mode-Specific Expressions, Prev: Writing Minor Modes, Up: Writing Modes Mode-Specific Indentation ------------------------- Some major modes provide functions which manage the indentation of the buffer they are installed in. These modes are usually those which are designed for a particular programming language; for example C mode understands how to indent C source and Lisp mode knows about Lisp code. To simplify matters there is a unified interface to the indentation process; each major mode simply sets the value of a buffer-local variable to the function used to indent a line in that buffer. This variable is then referenced by the functions which provide indentation. - Variable: mode-indent-line This buffer-local variable should contain a function when the buffer's major mode provides special indentation. The function should take one optional argument, the position of the line to indent. If the value of this argument is `nil' the current line should be indented. The function should set the indentation of the line to the correct depth then return the glyph position (*note Glyph Positions::.) of the first non-whitespace character. For example Lisp mode sets this variable to `lisp-indent-line', this function is defined as, (defun lisp-indent-line (&optional pos) (set-indent-pos (lisp-indent-pos (or pos (cursor-pos))))) Where the function `lisp-indent-pos' calculates the proper indentation for the line pointed to by its argument. For the functions dealing with indentation see *Note Indentation Functions::. File: jade.info, Node: Mode-Specific Expressions, Next: Mode-Specific Comments, Prev: Mode-Specific Indentation, Up: Writing Modes Mode-Specific Expressions ------------------------- Most programming use the concept of an "expression", Jade allows major modes to define two functions which define the syntax of an expression in a particular programming language. Commands exist which use these functions to allow the manipulation of expressions as entities in a buffer, much like words. - Variable: mode-forward-exp This buffer-local variable contains a function which calculates the position of the end of an expression in that language. The lambda-list of the function (i.e. its arguments) must be `(&optional COUNT POS)'. COUNT is the number of expressions to move forwards over (default is one), POS is the position to start from (default is the cursor position). The function should return the position of the character following the end of COUNT expressions starting from POS. - Variable: mode-backward-exp Similar to `mode-forward-exp' but works backwards from the character after the expression (at POS) to the start of the previous COUNT expressions. These functions can often be quite complex but their structure is usually the same; these two examples are taken from the Lisp mode, (defun lisp-forward-sexp (&optional number pos) "Return the position of the NUMBER'th next s-expression from POS." (unless number (setq number 1)) (while (> number 0) ;; Move `pos' over one expression ... (setq number (1- number))) pos) (defun lisp-backward-sexp (&optional number orig-pos) "Return the position of the NUMBER'th previous s-expression from ORIG-POS." (unless number (setq number 1)) (unless orig-pos (setq orig-pos (cursor-pos))) (let ((pos (copy-pos orig-pos))) (while (> number 0) ;; Move `pos' backwards over one expression ... (setq number (1- number))) pos)) File: jade.info, Node: Mode-Specific Comments, Prev: Mode-Specific Expressions, Up: Writing Modes Mode-Specific Comments ---------------------- When you wish to enter a comment in a piece of source code Jade has a command to do this (`insert-comment'); each major mode which wishes to allow comments (created by this command) must give the following variable a suitable function. - Variable: mode-comment-fun This buffer-local variable contains the function to call when a comment is to be entered, basically the `insert-comment' command just calls this function. - Function: find-comment-pos This function moves the cursor to a suitable position for inserting a comment in the current line. - Variable: comment-column Buffer-local variable containing the canonical column number which comments should begin at (used by the `find-comment-pos' function). If the line extends past this column the next tab stop after the end of the line is used instead. The following function is an example of what is needed in the `mode-comment-fun' variable; it is used by the C mode. (defun c-insert-comment () (interactive) (find-comment-pos) (insert "/* */") (goto-left-char 3)) File: jade.info, Node: Prompting, Next: Files, Prev: Writing Modes, Up: Programming Jade Prompting ========= The most common way to ask the user for a response is to encode the question in the command's interactive declaration (*note Interactive Declarations::.), sometimes this is inconvenient; functions are available which have the same effect as the code letters in an interactive declaration. The following two functions don't have an equivalent code for the interactive declaration. - Function: y-or-n-p QUESTION This function prompts the user for a single key response to the string QUESTION asking a question which can be answered yes or no. Returns `t' when QUESTION is answered with a `y' and `nil' when `n' is typed. - Function: yes-or-no-p QUESTION Similar to `y-or-n-p' but the answer must be either the word `yes' or the word `no' entered in full. This function should be used when a mistyped answer could be catastrophic (i.e. losing changes to a buffer). Returns `t' for `yes', `nil' for anything else. The following functions are the functions used by the `call-command' function to resolve interactive arguments. Note that these function don't return the string entered (except for `prompt-for-string') -- they return some Lisp object which the string entered represents somehow. - Function: prompt-for-file &optional PROMPT EXISTING START Prompts for the name of a file. PROMPT is the string to display at the head of the prompt, when EXISTING is non-`nil' only files which actually exist are allowed to be entered. The START argument may be a string defining the starting contents of the prompt. - Function: prompt-for-directory &optional PROMPT EXISTING START Prompts for the name of a directory, all arguments are similar to in the `prompt-for-file' function. - Function: prompt-for-buffer &optional PROMPT EXISTING DEFAULT This function prompts for a buffer object, if EXISTING is non-`nil' the buffer selected must exist, otherwise the buffer will be created if it doesn't already exist. DEFAULT is the value to return if the user enters the null string, if `nil' the current buffer is returned. Note that this returns the *actual buffer*, not its name as a string. - Function: prompt-for-symbol &optional PROMPT PREDICATE Prompt for a symbol, PROMPT is displayed at the head of the prompt buffer. If the PREDICATE argument is defined it is a predicate function; only symbols which when applied to the function PREDICATE return non-`nil' will be allowed to be entered. - Function: prompt-for-lisp &optional PROMPT Prompt for and return a Lisp object. - Function: prompt-for-function &optional PROMPT Prompts for a function. (prompt-for-function PROMPT) == (prompt-for-symbol PROMPT 'functionp) - Function: prompt-for-variable &optional PROMPT Prompts for a variable (a symbol whose value is not void). (prompt-for-variable PROMPT) == (prompt-for-symbol PROMPT 'boundp) - Function: prompt-for-command &optional PROMPT Prompts for a command (a function which may be called interactively). (prompt-for-command PROMPT) == (prompt-for-symbol PROMPT 'commandp) - Function: prompt-for-string &optional PROMPT Prompt for a string, whatever string is entered is returned as-is. - Function: prompt-for-number &optional PROMPT Prompts for a number which is then returned. The following function is useful when a number of options have to be chosen between, for example the menu command in Info-mode uses this function. - Function: prompt-from-list OPTION-LIST PROMPT &optional START Returns a selected choice from the list of options (strings) OPTION-LIST. PROMPT is the title displayed, START the optional starting choice. File: jade.info, Node: Files, Next: Processes, Prev: Prompting, Up: Programming Jade Files ===== Jade allows you to manipulate files in the operating system's filing system; a special type of Lisp object, a "file object", is used to represent files which have been opened for reading or writing (through the streams mechanism, *note Streams::.). Names of files are represented by strings, the syntax of file names is defined by the underlying operating system: Jade simply treats it as a string. * Menu: * File Names:: Files are named by a string * File Objects:: Lisp objects representing files * File Information:: Predicates on files * Manipulating Files:: Deleting, renaming and copying files * Reading Directories:: Getting a list of the files in a directory * Reading and Writing Files:: Accessing the contents of a file in one go File: jade.info, Node: File Names, Next: File Objects, Up: Files File Names ---------- A "file name" is a string identifying an individual file (or directory) in the filing system (i.e. the disk). The exact syntax of file names depends on the operating system. - Function: file-name-directory FILE-NAME This function returns the directory part of the file name string FILE-NAME. This is the substring of FILE-NAME defining the directory containing the file. (file-name-directory "/tmp/foo") => "/tmp/" (file-name-directory "foo") => "" (file-name-directory "foo/bar/") => "/foo/bar/" - Function: file-name-nondirectory FILE-NAME Returns the substring of the file name FILE-NAME which is *not* the directory part. (file-name-nondirectory "/tmp/foo") => "foo" (file-name-nondirectory "foo") => "foo" (file-name-nondirectory "foo/bar/") => "" - Function: file-name-concat &rest PARTS This function returns a file name constructed by concatenating each of the PARTS of the file name together. Each part is separated by the necessary string (i.e. `/' on Unix) when necessary. Note that each part may contain more than one component of the file name. (file-name-concat "/tmp" "foo" "bar") => "/tmp/foo/bar" (file-name-concat "/tmp/" "foo/" "bar") => "/tmp/foo/bar" (file-name-concat "/tmp/foo" "bar") => "/tmp/foo/bar" - Function: expand-file-name FILE-NAME &optional MAKE-ABSOLUTE This function expands the string FILE-NAME into a valid file name. Currently it only checks for a leading tilde character (`~') when running on Unix, if one is found it's expanded to the user's home directory. When the optional argument MAKE-ABSOLUTE is non-`nil' FILE-NAME is altered so that it is not relative to the current working directory. Generally this involves prefixing it by the absolute name of the current directory. (expand-file-name "~/src") => "/home/jsh/src" (expand-file-name "foo.c" t) => "/var/src/jade/foo.c" - Function: tmp-file-name This function returns the name of a file which, when created, may be used for temporary storage. Each time this function is called a unique name is computed. (tmp-file-name) => "/tmp/00088aaa" (tmp-file-name) => "/tmp/00088baa" File: jade.info, Node: File Objects, Next: File Information, Prev: File Names, Up: Files File Objects ------------ A file object is a Lisp object which represents a file in the filing system. Any file object may be used as a stream (either input or output) to access the contents of the file serially, *Note Streams::. * Menu: * Creating File Objects:: Opening files * Destroying File Objects:: Closing files * File Object Predicates:: Predicates for file objects * Functions on File Objects:: Functions operating on file objects File: jade.info, Node: Creating File Objects, Next: Destroying File Objects, Up: File Objects Creating File Objects ..................... - Function: open FILE-NAME MODE-STRING &optional FILE-OBJECT This function opens the file called FILE-NAME (*note File Names::.) and returns the file's object. The MODE-STRING argument is a string defining the access modes used to open the file with; this string is passed as-is to the C library's `fopen()' function. Usually one of the following strings is used, `r' Open an existing file for reading only. `w' Open the file for writing only, if the file exists it is truncated to zero length. Otherwise a new file is created. `a' Open the file for appending to, i.e. writing to the end of the file. If the file doesn't exist it is created. Other options exist; consult a C library manual for details. When the FILE-OBJECT argument is defined it should be a file object, the file it points to will be closed and the new file will be opened on this object. File: jade.info, Node: Destroying File Objects, Next: File Object Predicates, Prev: Creating File Objects, Up: File Objects Destroying File Objects ....................... The easiest way to close a file is simply to eliminate all references to it, subsequently the garbage collector will close it for you. It is better to close files explicitly though since only a limited number of files may be opened concurrently. - Function: close FILE-OBJECT This function closes the file pointed to by the file object FILE-OBJECT. Until a new file is opened on FILE-OBJECT any read/write accesses to it are illegal and an error will be signalled. File: jade.info, Node: File Object Predicates, Next: Functions on File Objects, Prev: Destroying File Objects, Up: File Objects File Object Predicates ...................... - Function: filep OBJECT This function returns `t' when its argument is a file object. - Function: file-bound-p FILE-OBJECT Returns `t' when the file object FILE-OBJECT is currently bound to a physical file (i.e. the `close' function hasn't been called on it yet). - Function: file-eof-p FILE-OBJECT This function returns `t' when the current position of the file object FILE-OBJECT is the end of the file (i.e. when reading a character from the file would return `nil'). File: jade.info, Node: Functions on File Objects, Prev: File Object Predicates, Up: File Objects Functions on File Objects ......................... - Function: flush-file FILE-OBJECT This function flushes any buffered output to the file object FILE-OBJECT to disk. Note that when using a file which was opened with the `+' option it's necessary to call this function when switching from reading to writing or vice versa. - Function: file-binding FILE-OBJECT Returns the name of the file which the file object FILE-OBJECT is currently bound to. - Function: read-file-until FILE-OBJECT REGEXP &optional IGNORE-CASE This function reads lines from the file object FILE-OBJECT until a line matching the regular expression REGEXP is found. The matching line is returned, or `nil' if the end of the file is reached. When the IGNORE-CASE option is non-`nil' all regexp matching is done case-insignificantly (except for matching ranges). File: jade.info, Node: File Information, Next: Manipulating Files, Prev: File Objects, Up: Files File Information ---------------- A number of functions exist which when given the name of a file return some information about that file. - Function: file-exists-p FILE-NAME Returns `t' when a file FILE-NAME exists. - Function: file-regular-p FILE-NAME Returns `t' when the file FILE-NAME is a `normal' file. This means that it isn't a directory, device, symbolic link or whatever. - Function: file-directory-p FILE-NAME Returns `t' when the file FILE-NAME is a directory. - Function: file-symlink-p FILE-NAME Returns `t' when the file FILE-NAME is a symbolic link. - Function: file-readable-p FILE-NAME Returns `t' when the file FILE-NAME is readable. - Function: file-writable-p FILE-NAME Returns `t' when the file FILE-NAME is writable. - Function: file-owner-p FILE-NAME Returns `t' when the ownership of the file FILE-NAME is the same as that of any files written by the editor. Note that currently this always returns `t' in the Amiga version. - Function: file-nlinks FILE-NAME Returns the number of hard links pointing to the file FILE-NAME. If FILE-NAME has only one name the number will be one. Note that this always returns one in the Amiga version of Jade. - Function: file-modes FILE-NAME This function returns the access permissions of the file FILE-NAME. This will be an integer whose format is undefined; it differs from operating system to operating system. - Function: set-file-modes FILE-NAME MODES This function sets the access permissions of the file FILE-NAME to the integer MODES (as returned by the `file-modes' function). - Function: file-modtime FILE-NAME Returns the system time at the last modification to the file FILE-NAME, this will be an integer. *Note System Time::. - Function: file-newer-than-file-p FILE-NAME1 FILE-NAME2 This function returns `t' if the file FILE-NAME1 was modified more recently than the file FILE-NAME2 was. (file-newer-than-file-p FILE1 FILE2) == (> (file-modtime FILE1) (file-modtime FILE2)) File: jade.info, Node: Manipulating Files, Next: Reading Directories, Prev: File Information, Up: Files Manipulating Files ------------------ - Command: delete-file FILE-NAME This function deletes the file called FILE-NAME. When called interactively FILE-NAME is prompted for. - Command: rename-file FILE-NAME NEW-NAME This function attempts to change the name of the file NEW-NAME to NEW-NAME. This won't work from one file system to another or if a file called NEW-NAME already exists, in these cases an error is signalled. This prompts for its arguments when called interactively. - Command: copy-file FILE-NAME DESTINATION-NAME Creates a new copy of the file FILE-NAME with the name DESTINATION-NAME. The access modes of the new file will be the same as those of the original file. The arguments are prompted for when this function is called interactively. File: jade.info, Node: Reading Directories, Next: Reading and Writing Files, Prev: Manipulating Files, Up: Files Reading Directories ------------------- - Function: directory-files DIRECTORY-NAME This function returns a list of the names of all files in the directory whose file name is DIRECTORY-NAME. The names in the list will be relative to the directory DIRECTORY-NAME, any directories in the list will have a `/' character appended to them. (directory-files "/tmp/foo" => ("bar" "subdir/" "xyz" "." "..") File: jade.info, Node: Reading and Writing Files, Prev: Reading Directories, Up: Files Reading and Writing Files ------------------------- - Function: read-file FILE-NAME This function returns a string containing the contents of the file called FILE-NAME. - Function: write-file FILE-NAME CONTENTS This function creates or overwrites the file called FILE-NAME with the string CONTENTS as its contents. File: jade.info, Node: Processes, Next: Miscellaneous Functions, Prev: Files, Up: Programming Jade Processes ========= When running on a Unix-style operating system (i.e. the X11 version) Jade allows you to launch and control an arbitrary number of subprocesses. These subprocesses can run either synchronously or asynchronously in respect to the editor; data can be sent to the stdin channel and any output from the process is automatically written to a programmer-defined Lisp stream. Currently there is *no* way to manipulate subprocesses in the Amiga version of Jade (sorry!). * Menu: * Process Objects:: Lisp objects associated with subprocesses * Asynchronous Processes:: Subprocesses running in parallel with Jade * Synchronous Processes:: Subprocesses which Jade runs serially * Process I/O:: Input and output with subprocesses * Process States:: Suspending subprocesses * Signalling Processes:: Sending signals to subprocesses * Process Information:: Information stored in a process object * Interactive Processes:: Shell mode lets the user interact with a subprocess